/*
 * Copyright 2008-2012 Centro Andaluz de Innovación y Tecnologías de la
 * Información y las Comunicaciones (CITIC). All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 *
 * Please contact CITIC - Edificio CITIC, C/ Marie Curie, 6 Parque
 * Tecnológico de Andalucía 29590 - Campanillas, Málaga, Spain
 * or visit www.citic.es, if you need additional information or
 * have any questions.
 */
package es.citic.puedes.youtube;

import java.util.List;

import es.citic.puedes.youtube.model.Category;
import es.citic.puedes.youtube.model.OrderBy;
import es.citic.puedes.youtube.model.StandarVideos;
import es.citic.puedes.youtube.model.UserPreferences;
import es.citic.puedes.youtube.model.YouTubeContact;
import es.citic.puedes.youtube.model.YouTubePlayList;
import es.citic.puedes.youtube.model.YouTubePlayListEntry;
import es.citic.puedes.youtube.model.YouTubeResult;
import es.citic.puedes.youtube.model.YouTubeType;
import es.citic.puedes.youtube.model.YouTubeUser;
import es.citic.puedes.youtube.model.YouTubeVideo;
import es.citic.puedes.youtube.model.YouTubeVideoMinimal;

/**
 * interface that provides the complete functionality of the YouTube service
 * 
 * 
 */
public interface IYouTubeManager {

	/**
	 * Register an user in the YouTube service
	 * 
	 * @param userId
	 *            user Id for the PUEDeS platform
	 * @param userName
	 *            YouTube account username
	 * @param password
	 *            YouTube account password
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void registreUser(Integer userId, String userName, String password)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * changes the username or password from a user in the YouTube service
	 * 
	 * @param userId
	 *            user Id for the PUEDeS platform
	 * @param userName
	 *            YouTube account username to modify
	 * @param password
	 *            YouTube account password to modify
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void changeUser(Integer userId, String userName, String password)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * deletes an user from YouTube service
	 * 
	 * @param userId
	 *            user Id for the PUEDeS platform
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void deleteUser(Integer userId) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * Gets the videos uploaded by a YouTube user
	 * 
	 * @param user
	 *            user profile
	 * @return a model YouTubeVideo object list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	List<YouTubeVideoMinimal> getUserVideos(YouTubeUser user)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * Gets the videos uploaded by a YouTube user by paging
	 * 
	 * @param user
	 *            user profile
	 * 
	 * @param indexStart
	 *            offset to get the elements. Must be greater than 0
	 * @param maxResults
	 *            max number of elements to return
	 * @return a model YouTubeVideo object list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	List<YouTubeVideoMinimal> getUserVideos(YouTubeUser user,
			Integer indexStart, Integer maxResults) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * searches videos and playlists using several parameters
	 * 
	 * @param type
	 *            search type (videos, playlists or all)
	 * @param order
	 *            search order (view count, rating, relevance, published)
	 * @param keywords
	 *            keywords assigned to the video or playlist to search
	 * @return a model YouTubeResult object that contains the found videos or
	 *         playlists
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	YouTubeResult search(YouTubeType type, OrderBy order, List<String> keywords)
			throws YouTubeException, SecurityException;

	/**
	 * searches videos and playlists using several parameters and paging
	 * 
	 * @param type
	 *            search type (videos, playlists or all)
	 * @param order
	 *            search order (view count, rating, relevance, published)
	 * @param keywords
	 *            keywords assigned to the video or playlist to search
	 * @param indexStart
	 *            offset to get the elements. Must be greater than 0
	 * @param maxResults
	 *            max number of elements to return
	 * @return a model YouTubeResult object that contains the found videos or
	 *         playlists
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */

	YouTubeResult search(YouTubeType type, OrderBy order,
			List<String> keywords, Integer indexStart, Integer maxResults)
			throws YouTubeException, SecurityException;

	/**
	 * searches videos by paging using categories apart from other parameters
	 * 
	 * @param category
	 *            category to explore
	 * @param order
	 *            search order (view count, rating, relevance, published)
	 * @param keyWords
	 *            keywords assigned to the video to search
	 * 
	 * @param indexStart
	 *            offset to get the elements. Must be greater than 0
	 * @param maxResults
	 *            max number of elements to return
	 * @return a model YouTubeVideoMinimal object list that contains the found
	 *         videos
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	List<YouTubeVideoMinimal> explore(Category category, OrderBy order,
			List<String> keyWords, Integer indexStart, Integer maxResults)
			throws YouTubeException, SecurityException;

	/**
	 * searches videos using categories apart from other parameters
	 * 
	 * @param category
	 *            category to explore
	 * @param order
	 *            search order (view count, rating, relevance, published)
	 * @param keyWords
	 *            keywords assigned to the video to search
	 * @return a model YouTubeVideoMinimal object list that contains the found
	 *         videos
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	List<YouTubeVideoMinimal> explore(Category category, OrderBy order,
			List<String> keyWords) throws YouTubeException, SecurityException;

	/**
	 * gets a YouTube video using an youtubeVideoId
	 * 
	 * @param youtubeVideoId a youtubeVideoId
	 * @return a model YouTubeVideo object
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	YouTubeVideo getVideo(String youtubeVideoId) throws YouTubeException, SecurityException;

	/**
	 * Gets the playlists from a YouTube user
	 * 
	 * @param user
	 *            user profile
	 * @return a model YouTubePlayList object list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	List<YouTubePlayList> getPlayLists(YouTubeUser user)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * Gets the playlists from a YouTube user by paging
	 * 
	 * @param user
	 *            user profile
	 * @param indexStart
	 *            offset to get the elements. Must be greater than 0
	 * @param maxResults
	 *            max number of elements to return
	 * @return a model YouTubePlayList object list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	List<YouTubePlayList> getPlayLists(YouTubeUser user, Integer indexStart,
			Integer maxResults) throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * gets the YouTube playlist entries by paging using a playlist id
	 * 
	 * @param playListId playlist id
	 * @param indexStart offset to get the elements. Must be greater than 0
	 * @param maxResults max number of elements to return
	 * @return a model YouTubePlayListEntry object list
	 * @throws YouTubeException If any error in the service appears
	 */
	List<YouTubePlayListEntry> getPlayList(String playListId, Integer indexStart, Integer maxResults) throws YouTubeException, SecurityException;

	/**
	 * gets the entries of a YouTube playlist using a playlist id
	 * 
	 * @param playListId playlist id
	 * @return a model YouTubePlayListEntry object list
	 * @throws YouTubeException If any error in the service appears
	 */
	List<YouTubePlayListEntry> getPlayList(String playListId) throws YouTubeException, SecurityException;

	/**
	 * uploads a video to the YouTube web
	 * 
	 * @param user
	 *            user profile
	 * @param video
	 *            a model YouTubeVideo object that contains the video to upload
	 * @param videoPath
	 *            path with the video location
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void insertVideo(YouTubeUser user, YouTubeVideo video, String videoPath)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * adds a rating for a YouTube video
	 * 
	 * @param user
	 *            user profile
	 * @param videoID
	 *            id from video to rate
	 * @param value
	 *            value between 1 and 5 to indicate if you like or dislike the
	 *            video
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void addRating(YouTubeUser user, String videoID, Integer value)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * adds a comment for a YouTube video
	 * 
	 * @param user
	 *            user profile
	 * @param videoID
	 *            id from video to add
	 * @param comment
	 *            text for comment a video
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void addComment(YouTubeUser user, String videoID, String comment)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * deletes a YouTube video uploaded by an user
	 * 
	 * @param user
	 *            user profile
	 * @param videoID
	 *            id from video to delete
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void deleteVideo(YouTubeUser user, String videoID) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * gets the favorite YouTube videos from an user by paging
	 * 
	 * @param user
	 *            user profile
	 * 
	 * @param indexStart
	 *            offset to get the elements. Must be greater than 0
	 * @param maxResults
	 *            max number of elements to return
	 * @return a model YouTubeVideoMinimal object list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */

	List<YouTubeVideoMinimal> getFavorites(YouTubeUser user,
			Integer indexStart, Integer maxResults) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * gets the favorite YouTube videos from an user
	 * 
	 * @param user
	 *            user profile
	 * @return a model YouTubeVideoMinimal object list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	List<YouTubeVideoMinimal> getFavorites(YouTubeUser user)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * adds a video to the YouTube favorite videos from an user
	 * 
	 * @param user
	 *            user profile
	 * @param videoID
	 *            id from video to add
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void addFavorites(YouTubeUser user, String videoID)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * deletes a video from the favorites of an user
	 * 
	 * @param user
	 *            user profile
	 * @param favoriteID
	 *            id from video to delete
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void deleteFavorites(YouTubeUser user, String favoriteID)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * adds a new playlist to the user YouTube playlists
	 * 
	 * @param user
	 *            user profile
	 * @param title
	 *            playlist title
	 * @param description
	 *            playlist description
	 * @return id of the new playlist created
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */

	String addPlayList(YouTubeUser user, String title, String description)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * deletes a playlist from the user YouTube playlists
	 * 
	 * @param user
	 *            user profile
	 * @param playListID
	 *            id from playlist to delete
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void deletePlayList(YouTubeUser user, String playListID)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * adds a video to a YouTube playlist from an user
	 * 
	 * @param user
	 *            user profile
	 * @param videoID
	 *            id from video to add
	 * @param playListID
	 *            playlist id
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void addVideoPlayList(YouTubeUser user, String videoID, String playListID) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * 
	 * deletes a video from a YouTube playlist of an user. If the video exists
	 * more than once, the last occurrence will be removed
	 * 
	 * @param user
	 *            user profile
	 * @param playlistVideoID
	 *            id from video to delete
	 * @param playListID
	 *            playlist id
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void deleteVideoPlayList(YouTubeUser user, String playlistVideoID, String playListID)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * filters a video list by a text
	 * 
	 * @param filter
	 *            text to look up in the descriptions, titles and keywords of
	 *            the videos from the list
	 * @param videoList
	 *            video list to look up
	 * @return a YouTubeVideoMinimal object list with the videos found
	 */
	List<YouTubeVideoMinimal> filterList(String filter,
			List<YouTubeVideoMinimal> videoList)throws YouTubeException, SecurityException;

	/**
	 * gets the YouTube contact list from an user. Only gets the contacts
	 * accepted previously
	 * 
	 * @param user
	 *            user profile
	 * @return a model YouTubeContact object list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	List<YouTubeContact> getContacts(YouTubeUser user) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * adds a YouTube user to the contact list of the user authenticated
	 * 
	 * @param user
	 *            user profile
	 * @param username
	 *            username of a YouTube user to add as contact
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void addContact(YouTubeUser user, String userName) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * deletes a YouTube user from the contact list of the user authenticated
	 * 
	 * @param user
	 *            user profile
	 * @param userName
	 *            username of a YouTube user to delete from the contact list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void deleteContact(YouTubeUser user, String userName)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * accepts or rejects a friend request from a contact for a YouTube user
	 * 
	 * @param user
	 *            user profile
	 * @param userName
	 *            contact username to accept or reject as a friend
	 * @param accept
	 *            true to accept, false to reject
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 * 
	 */
	void acceptContact(YouTubeUser user, String userName, boolean accept)
			throws YouTubeException, YouTubeAuthException, SecurityException;

	/**
	 * gets the YouTube profile from an user
	 * 
	 * @param userId
	 *            user id for the PUEDeS platform
	 * @return a model YouTubeUser object
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	YouTubeUser getUserProfile(Integer userId) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * gets the most recent and most viewed videos from YouTube
	 * 
	 * @return a model StandarVideos object with the most recent video list and
	 *         most viewed video list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	StandarVideos getStandarVideos() throws YouTubeException, SecurityException;

	/**
	 * gets the most recent and most viewed videos from YouTube by paging
	 * 
	 * @param indexStart
	 *            offset to get the elements. Must be greater than 0
	 * @param maxResults
	 *            max number of elements to return
	 * @return a model StandarVideos object with the most recent video list and
	 *         most viewed video list
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	StandarVideos getStandarVideos(Integer indexStart, Integer maxResults)
			throws YouTubeException, SecurityException;

	/**
	 * updates a video uploaded by an user
	 * 
	 * @param user
	 *            user profile
	 * @param youtubeVideoId youtubeVideoId
	 * @param title
	 *            new video title
	 * @param description
	 *            new video description
	 * @param keyWords
	 *            new video keywords
	 * @throws YouTubeException
	 *             If any error in the service appears
	 * @throws YouTubeAuthException
	 *             If the service is unable to authenticate the user
	 */
	void updateVideo(YouTubeUser user, String youtubeVideoId, String title,
			String description, List<String> keyWords) throws YouTubeException,
			YouTubeAuthException, SecurityException;

	/**
	 * sets the preferences for a YouTube user
	 * 
	 * @param userId
	 *            PUEDeS platform user
	 * @param preferences
	 *            preferences to set
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	void setPreferences(Integer userId, List<String> preferences)
			throws YouTubeException, SecurityException;

	/**
	 * marks the preferences for a YouTube user
	 * 
	 * @param userId
	 *            PUEDeS platform user
	 * @param preferences
	 *            preferences to set
	 * @param value
	 *            positive or negative value to indicate if you like or dislike
	 *            the video
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	void setMarkPreferences(Integer userId, List<String> preferences,
			boolean value) throws YouTubeException, SecurityException;

	/**
	 * gets the preferences from a YouTube user
	 * 
	 * @param userId
	 *            PUEDeS platform user
	 * @return a model UserPreferences object that contais the preferences from
	 *         a youTube user
	 * @throws YouTubeException
	 *             If any error in the service appears
	 */
	UserPreferences getPreferences(Integer userId) throws YouTubeException, SecurityException;

	
//	//to delete..
//	/**
//	 * registers the YouTubeManager service into the DataBaseManager service,
//	 * creating the data model in the database
//	 * 
//	 * 
//	 * @throws YouTubeException
//	 *             if any problem in the register of the service appears
//	 */
//	void install() throws YouTubeException;
//
//	//to delete..
//	/**
//	 * cancels the YouTubeManager service into the DataBaseManager service,
//	 * removing the data model from the database
//	 * 
//	 * 
//	 * @throws YouTubeException
//	 *             if any problem in the cancellation of the service appears
//	 */
//	void unInstall() throws YouTubeException;

}
